<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Configures a callback to be used as an authorizer to limit what a statement can do</title>
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-base.css" />
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-medium.css" />

 </head>
 <body class="docs"><div class="navbar navbar-fixed-top">
  <div class="navbar-inner clearfix">
    <ul class="nav" style="width: 100%">
      <li style="float: left;"><a href="sqlite3.querysingle.html">« SQLite3::querySingle</a></li>
      <li style="float: right;"><a href="sqlite3.version.html">SQLite3::version »</a></li>
    </ul>
  </div>
</div>
<div id="breadcrumbs" class="clearfix">
  <ul class="breadcrumbs-container">
    <li><a href="index.html">PHP Manual</a></li>
    <li><a href="class.sqlite3.html">SQLite3</a></li>
    <li>Configures a callback to be used as an authorizer to limit what a statement can do</li>
  </ul>
</div>
<div id="layout">
  <div id="layout-content"><div id="sqlite3.setauthorizer" class="refentry">
 <div class="refnamediv">
  <h1 class="refname">SQLite3::setAuthorizer</h1>
  <p class="verinfo">(PHP 8)</p><p class="refpurpose"><span class="refname">SQLite3::setAuthorizer</span> &mdash; <span class="dc-title">Configures a callback to be used as an authorizer to limit what a statement can do</span></p>

 </div>

 <div class="refsect1 description" id="refsect1-sqlite3.setauthorizer-description">
  <h3 class="title">说明</h3>
  <div class="methodsynopsis dc-description">
   <span class="modifier">public</span> <span class="methodname"><strong>SQLite3::setAuthorizer</strong></span>(<span class="methodparam"><span class="type">?</span><span class="type"><span class="type"><a href="language.types.callable.html" class="type callable">callable</a></span><span class="type"></span></span> <code class="parameter">$callback</code></span>): <span class="type">bool</span></div>

  <p class="para rdfs-comment">
   Sets a callback that will be called by SQLite every time an action is performed
   (reading, deleting, updating, etc.). This is used when preparing a SQL statement from
   an untrusted source to ensure that the SQL statements do not try to access data they
   are not allowed to see, or that they do not try to execute malicious statements that
   damage the database. For example, an application may allow a user to enter arbitrary
   SQL queries for evaluation by a database. But the application does not want the user to
   be able to make arbitrary changes to the database. An authorizer could then be put in
   place while the user-entered SQL is being prepared that disallows everything except
   SELECT statements.
  </p>
  <p class="para">
   The authorizer callback may be called multiple times for each statement prepared by
   SQLite. A <code class="literal">SELECT</code> or <code class="literal">UPDATE</code> query will call the
   authorizer for every column that would be read or updated.
  </p>
  <p class="para">
   The authorizer is called with up to five parameters. The first parameter is always
   given, and is an <span class="type">int</span> (action code) matching a constant from
   <code class="literal">SQLite3</code>. The other parameters are only passed for some actions. The
   following table describes the second and third parameters according to the action:
   <table class="doctable table">
    <caption><strong>List of action codes and parameters</strong></caption>
    
     <thead>
      <tr>
       <th>Action</th>
       <th>Second parameter</th>
       <th>Third parameter</th>
      </tr>

     </thead>

     <tbody class="tbody">
      <tr><td><strong><code>SQLite3::CREATE_INDEX</code></strong></td><td>Index Name</td><td>Table Name</td></tr>

      <tr><td><strong><code>SQLite3::CREATE_TABLE</code></strong></td><td>Table Name</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::CREATE_TEMP_INDEX</code></strong></td><td>Index Name</td><td>Table Name</td></tr>

      <tr><td><strong><code>SQLite3::CREATE_TEMP_TABLE</code></strong></td><td>Table Name</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::CREATE_TEMP_TRIGGER</code></strong></td><td>Trigger Name</td><td>Table Name</td></tr>

      <tr><td><strong><code>SQLite3::CREATE_TEMP_VIEW</code></strong></td><td>View Name</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::CREATE_TRIGGER</code></strong></td><td>Trigger Name</td><td>Table Name</td></tr>

      <tr><td><strong><code>SQLite3::CREATE_VIEW</code></strong></td><td>View Name</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::DELETE</code></strong></td><td>Table Name</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::DROP_INDEX</code></strong></td><td>Index Name</td><td>Table Name</td></tr>

      <tr><td><strong><code>SQLite3::DROP_TABLE</code></strong></td><td>Table Name</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::DROP_TEMP_INDEX</code></strong></td><td>Index Name</td><td>Table Name</td></tr>

      <tr><td><strong><code>SQLite3::DROP_TEMP_TABLE</code></strong></td><td>Table Name</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::DROP_TEMP_TRIGGER</code></strong></td><td>Trigger Name</td><td>Table Name</td></tr>

      <tr><td><strong><code>SQLite3::DROP_TEMP_VIEW</code></strong></td><td>View Name</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::DROP_TRIGGER</code></strong></td><td>Trigger Name</td><td>Table Name</td></tr>

      <tr><td><strong><code>SQLite3::DROP_VIEW</code></strong></td><td>View Name</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::INSERT</code></strong></td><td>Table Name</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::PRAGMA</code></strong></td><td>Pragma Name</td><td>First argument passed to the pragma, or <strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::READ</code></strong></td><td>Table Name</td><td>Column Name</td></tr>

      <tr><td><strong><code>SQLite3::SELECT</code></strong></td><td><strong><code>null</code></strong></td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::TRANSACTION</code></strong></td><td>Operation</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::UPDATE</code></strong></td><td>Table Name</td><td>Column Name</td></tr>

      <tr><td><strong><code>SQLite3::ATTACH</code></strong></td><td>Filename</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::DETACH</code></strong></td><td>Database Name</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::ALTER_TABLE</code></strong></td><td>Database Name</td><td>Table Name</td></tr>

      <tr><td><strong><code>SQLite3::REINDEX</code></strong></td><td>Index Name</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::ANALYZE</code></strong></td><td>Table Name</td><td><strong><code>null</code></strong></td></tr>

      <tr><td><strong><code>SQLite3::CREATE_VTABLE</code></strong></td><td>Table Name</td><td>Module Name</td></tr>

      <tr><td><strong><code>SQLite3::DROP_VTABLE</code></strong></td><td>Table Name</td><td>Module Name</td></tr>

      <tr><td><strong><code>SQLite3::FUNCTION</code></strong></td><td><strong><code>null</code></strong></td><td>Function Name</td></tr>

      <tr><td><strong><code>SQLite3::SAVEPOINT</code></strong></td><td>Operation</td><td>Savepoint Name</td></tr>

      <tr><td><strong><code>SQLite3::RECURSIVE</code></strong></td><td><strong><code>null</code></strong></td><td><strong><code>null</code></strong></td></tr>

     </tbody>
    
   </table>

  </p>
  <p class="para">
   The 4th parameter will be the name of the database (<code class="literal">&quot;main&quot;</code>,
   <code class="literal">&quot;temp&quot;</code>, etc.) if applicable.
  </p>
  <p class="para">
   The 5th parameter to the authorizer callback is the name of the inner-most trigger or
   view that is responsible for the access attempt or <strong><code>null</code></strong> if this access attempt is
   directly from top-level SQL code.
  </p>
  <p class="para">
   When the callback returns <strong><code>SQLite3::OK</code></strong>, that means the operation
   requested is accepted. When the callback returns <strong><code>SQLite3::DENY</code></strong>,
   the call that triggered the authorizer will fail with an error message explaining that
   access is denied.
  </p>
  <p class="para">
   If the action code is <strong><code>SQLite3::READ</code></strong> and the callback returns
   <strong><code>SQLite3::IGNORE</code></strong> then the prepared statement is
   constructed to substitute a <strong><code>null</code></strong> value in place of the table column that would have
   been read if <strong><code>SQLite3::OK</code></strong> had been returned. The
   <strong><code>SQLite3::IGNORE</code></strong> return can be used to deny an untrusted user
   access to individual columns of a table.
  </p>
  <p class="para">
   When a table is referenced by a <code class="literal">SELECT</code> but no column values are
   extracted from that table (for example in a query like <code class="literal">&quot;SELECT count(*) FROM
   table&quot;</code>) then the <strong><code>SQLite3::READ</code></strong> authorizer callback is
   invoked once for that table with a column name that is an empty string.
  </p>
  <p class="para">
   If the action code is <strong><code>SQLite3::DELETE</code></strong> and the callback returns
   <strong><code>SQLite3::IGNORE</code></strong> then the DELETE operation proceeds but the
   truncate optimization is disabled and all rows are deleted individually.
  </p>
  <p class="para">
   Only a single authorizer can be in place on a database connection at a time. Each call
   to <span class="methodname"><strong>SQLite3::setAuthorizer()</strong></span> overrides the previous call. Disable the
   authorizer by installing a <strong><code>null</code></strong> callback. The authorizer is disabled by default.
  </p>
  <p class="para">
   The authorizer callback must not do anything that will modify the database connection
   that invoked the authorizer callback.
  </p>
  <p class="para">
   Note that the authorizer is only called when a statement is prepared, not when it&#039;s
   executed.
  </p>
  <p class="para">
   More details can be found in the
   <a href="http://sqlite.org/c3ref/set_authorizer.html" class="link external">&raquo;&nbsp;SQLite3 documentation</a>.
  </p>
 </div>


 <div class="refsect1 parameters" id="refsect1-sqlite3.setauthorizer-parameters">
  <h3 class="title">参数</h3>
  <dl>
   
    <dt>
<code class="parameter">callback</code></dt>

    <dd>

     <p class="para">
      The <span class="type"><a href="language.types.callable.html" class="type callable">callable</a></span> to be called.
     </p>
     <p class="para">
      If <strong><code>null</code></strong> is passed instead, this will disable the current authorizer callback.
     </p>
    </dd>

   
  </dl>

 </div>


 <div class="refsect1 returnvalues" id="refsect1-sqlite3.setauthorizer-returnvalues">
  <h3 class="title">返回值</h3>
  <p class="para">
   成功时返回 <strong><code>true</code></strong>， 或者在失败时返回 <strong><code>false</code></strong>。
  </p>
 </div>


 <div class="refsect1 errors" id="refsect1-sqlite3.setauthorizer-errors">
  <h3 class="title">错误／异常</h3>
  <p class="para">
   This method doesn&#039;t throw any error, but if an authorizer is enabled and returns an
   invalid value, the statement preparation will throw an error (or exception, depending
   on the use of the <span class="methodname"><a href="sqlite3.enableexceptions.html" class="methodname">SQLite3::enableExceptions()</a></span> method).
  </p>
 </div>


 <div class="refsect1 examples" id="refsect1-sqlite3.setauthorizer-examples">
  <h3 class="title">范例</h3>
  <div class="example" id="example-1954">
   <p><strong>示例 #1 <span class="methodname"><strong>SQLite3::setAuthorizer()</strong></span> example</strong></p>
   <div class="example-contents"><p>
     This only allows access to reading, and only some columns of the
     <code class="literal">users</code> table will be returned. Other columns will be replaced with
     <strong><code>null</code></strong>.
   </p></div>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$db&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">SQLite3</span><span style="color: #007700">(</span><span style="color: #DD0000">'data.sqlite'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$db</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">exec</span><span style="color: #007700">(</span><span style="color: #DD0000">'CREATE&nbsp;TABLE&nbsp;users&nbsp;(id,&nbsp;name,&nbsp;password);'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$db</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">exec</span><span style="color: #007700">(</span><span style="color: #DD0000">'INSERT&nbsp;INTO&nbsp;users&nbsp;VALUES&nbsp;(1,&nbsp;\'Pauline\',&nbsp;\'Snails4eva\');'</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$allowed_columns&nbsp;</span><span style="color: #007700">=&nbsp;[</span><span style="color: #DD0000">'id'</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'name'</span><span style="color: #007700">];<br /><br /></span><span style="color: #0000BB">$db</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">setAuthorizer</span><span style="color: #007700">(function&nbsp;(</span><span style="color: #0000BB">int&nbsp;$action</span><span style="color: #007700">,&nbsp;...</span><span style="color: #0000BB">$args</span><span style="color: #007700">)&nbsp;use&nbsp;(</span><span style="color: #0000BB">$allowed_columns</span><span style="color: #007700">)&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(</span><span style="color: #0000BB">$action&nbsp;</span><span style="color: #007700">===&nbsp;</span><span style="color: #0000BB">SQLite3</span><span style="color: #007700">::</span><span style="color: #0000BB">READ</span><span style="color: #007700">)&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;list(</span><span style="color: #0000BB">$table</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$column</span><span style="color: #007700">)&nbsp;=&nbsp;</span><span style="color: #0000BB">$args</span><span style="color: #007700">;<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(</span><span style="color: #0000BB">$table&nbsp;</span><span style="color: #007700">===&nbsp;</span><span style="color: #DD0000">'users'&nbsp;</span><span style="color: #007700">&amp;&amp;&nbsp;</span><span style="color: #0000BB">in_array</span><span style="color: #007700">(</span><span style="color: #0000BB">$column</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$allowed_columns</span><span style="color: #007700">)&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;</span><span style="color: #0000BB">SQLite3</span><span style="color: #007700">::</span><span style="color: #0000BB">OK</span><span style="color: #007700">;<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;</span><span style="color: #0000BB">SQLite3</span><span style="color: #007700">::</span><span style="color: #0000BB">IGNORE</span><span style="color: #007700">;<br />&nbsp;&nbsp;&nbsp;&nbsp;}<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;</span><span style="color: #0000BB">SQLite3</span><span style="color: #007700">::</span><span style="color: #0000BB">DENY</span><span style="color: #007700">;<br />});<br /><br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$db</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">querySingle</span><span style="color: #007700">(</span><span style="color: #DD0000">'SELECT&nbsp;*&nbsp;FROM&nbsp;users&nbsp;WHERE&nbsp;id&nbsp;=&nbsp;1;'</span><span style="color: #007700">));</span>
</span>
</code></div>
   </div>


   <div class="example-contents"><p>以上例程会输出：</p></div>
   <div class="example-contents screen">
<div class="cdata"><pre>
Array
(
    [id] =&gt; 1
    [name] =&gt; Pauline
    [password] =&gt;
)
</pre></div>
   </div>
  </div>
 </div>


</div></div></div></body></html>